This document describes TCPSerial which simulates a serial driver and modem using a TCP/IP connection allowing one to use Apple Remote Access and other programs that normally only work with modems over the Internet.
Installation and setup
To install the driver and ARA script, simply drag them to the closed System Folder in the Finder. It will place them both in your Extensions folder, where they belong. You must have System 7.0 and either MacTCP or Open Transport installed to use this driver. TCPSerial is compatible with Open Transport 1.1 and later, but it uses the MacTCP compatibility interface to it.
Once you have installed these files and rebooted your machine, you need to configure Apple Remote Access to use them if that is your goal. Open the "Remote Access Setup" Control Panel and select either the "TCP #1" or "TCP #2" port (they are equivalent). You also need to select "TCP" in the "Modem:" pop-up to the left of the port selection. If you check the "ignore dial tone" check box below the Modem pop-up, TCPSerial will turn off the data compression normally done by ARA which may improve performance in certain cases. The other options in the top half of the Remote Access Setup dialog are ignored.
Having configured Remote Access Setup correctly, you also need to create an ARA connection document that uses TCP. Create a new connection document by launching "Remote Access Client" or "Remote Access Personal" (depending on which version of ARA you have installed) and enter the IP address or DNS name of the server you want to call in the "Number:" field. The rest of the connect document is as normal. If necessary, you may append a colon and port number to the address or DNS name to specify which port to call, by default it calls and listens on port 3454 which has been assigned to this service.
This version of TCPSerial will not work with Apple's ARA Multiport Server, which is normally bundled with serial port hardware and will only work with that hardware. It will work with the Remote Access Personal Server which can be used to receive as well as make calls using TCP.
This is all you need to know to use the driver with Apple Remote Access. If you want to know more of the technical details about how it works, they are described below. Otherwise, install the two files and reboot, configure the Remote Access Setup control panel to use them, and create a connection document to place a call. You of course must do this on two machines if one is answering a call placed by the other. The connection document is only required on the calling machine.
Permission is granted to use this software for noncommercial education and research purposes. Permission to copy, distribute, modify or otherwise create derivative works of this software is not granted.
This software is provided as is, without representation as to its fitness for any purpose, and without warranty of any kind, either express or implied, including without limitation the implied warranties of merchantability and fitness for a particular purpose. The Regents of the University of Michigan shall not be liable for any damages, including special, indirect, incidental, or consequential damages, with respect to any claim arising out of or in connection with the use of the software, even if it has been or is hereafter advised of the possibility of such damages.
TCPSerial Serial Driver Description
The TCP Serial Driver is makes it possible to use the serial driver interface to open and receive TCP connections via MacTCP. This is a standard driver which accepts all the Control commands accepted by the normal serial drivers (although some of them do nothing). It registers itself with the Communications Resource Manager (CRM) so that any program which uses the CRM to find serial drivers will be able to use this driver. As with other serial drivers, it actually consists of a pair of drivers called TCPSer1In and TCPSer1Out. It also registers a second pair of drivers called TCPSer2In and TCPSer2Out so that two programs can use this driver at the same time. They are equivalent to the other pair and everything said below about one of them applies to the other also.
Within each pair, it is not necessary to use both drivers. If a program opens only one of them, then that one can be used for both input and output. If both are opened, then .TCPSerxIn must be used for input and .TCPSerXOut for output. In this case it is possible to do both input and output simultaneously, while if only one is opened, no operation will begin until all previous ones have completed.
In addition to implementing the serial driver interface, this program also simulates a subset of the Hayes modem command set. This allows you to configure the TCP connection, make calls, answer calls, etc. These commands are recognized only when the driver is in command mode. One can enter command mode from online mode in one of two ways. If a write operation consists of exactly the three characters "+++" then the driver will enter command mode but not close the connection. This is generally impossible to do from a terminal emulator since each of the pluses will be passed to the tool as a separate write operation. The other way to enter command mode is to ask the driver to drop DTR. This also closes any active connection. You must raise DTR again before the driver will recognize any output.
If the connection closes spontaneously, the driver will return the message "cr/lf/NO CARRIER/cr/lf" the next time the program reads from the driver. For this to work correctly, the currently active program must call SystemTask (or the equivalent) periodically. In general this is a requirement for commands to work correctly. Since the driver can be called from interrupt routines and some commands can't be executed at that time, commands are deferred to SystemTask time if possible.
The code used to install the driver is an adaptation of driver.c version 2.1.8 by Pete Resnick (resnick@cogsci.uiuc.edu) and others.
Modem Command Description
The commands recognized are as follows:
ATZ
AT&F
Both of these disconnect any existing call and reset the configuration to the default state. There is no way to specify a "stored configuration" for use by ATZ, so it is currently a synonym for AT&F, which loads the "factory default configuration."
ATE[0|1]
This commands turns on or off (for 1 or 0 respectively) echoing of commands.
ATQ[0|1]
This turns on or of (for 0 or 1 respectively) command responses such as "OK", "ERROR", etc.
ATM[0-9]
ATL[0-9]
These commands, which control the modem speaker, are ignored.
AT*CConfig data
Anything after the *C is used to set the configuration of TCP. Currently the only thing recognized is the string "Port nnn" which sets the remote port for an outgoing connection or the local port for an incoming connection. The remote port is always zero (meaning any port) for an incoming connection and the local port is always zero (meaning the system should pick one) for an outgoing connection.
AT*O
This prints out the current configuration of the tool (assuming that ATQ1 has not been given eariler).
ATA
This command waits for an incoming call. When one is received, the message "CONNECT" is returned, assuming the driver is not in quiet mode (ATQ1).
ATDTxxxxx
This is the command used to place a call. Everything after the DT is taken to be the remote address and can be either an IP address or a DNS name. Opionally, it is possible to append ":port" to the address or DNS name to specify which remote port to connect to. When the connection is open, the driver returns the message "CONNECT". If it fails it returns "NO CARRIER". Synonyms for this command are ATTD, ATDP, and ATPD.
ATH[0]
This command causes the current connection (if any) to be closed. It is only relevant if you got into command mode using the "+++" trick described above.
ATO[0]
This will get you back online if you entered command mode using the "+++" trick. Otherwise it is an error.
AT*D 'Config string' 'Phone number'
The two parameters can be enclosed in either single quotes or double quotes. If they contain no internal blanks, the quotes are not necessary. This command is a way to specify all the information necessary to make a connection on one command. It is essentially a combination of the following commands in this order:
ATZ
AT*CConfig string
ATDTPhone number or ATA (if the phone number is null or missing)
The reason for having this command is so that it is possible for the Apple Remote Access script to issue one command and then wait essentially forever for it to complete. Since these scripts are executed during boot when no one is calling SystemTask, commands may take a very long time to complete and executing a series of them is difficult to do reliably. It also has the advantage of being considerably faster than executing the command separately.
Version history
Version 1.0: Internal University of Michigan release
Version 1.0.1: First public release. Port number changed to officially assigned port number
last updated 30 May 1996 by Mike Alexander <mta@umich.edu>
